IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3x/dslib.z/dslib

Text File | 2002-10-03 | 20.4 KB | 331 lines

ddddsssslllliiiibbbb((((3333XXXX))))                                                            ddddsssslllliiiibbbb((((3333XXXX))))



NNNNAAAAMMMMEEEE
     dslib: dsopen, dsclose - communicate with generic SCSI devices

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<ddddsssslllliiiibbbb....hhhh>>>>

     ssssttttrrrruuuucccctttt ddddssssrrrreeeeqqqq ****ddddssssooooppppeeeennnn((((ooooppppaaaatttthhhh,,,, ooooffffllllaaaaggggssss))))

     ddddsssscccclllloooosssseeee((((ddddsssspppp))))

     ddddssss____sssshhhhoooowwwwccccmmmmdddd((((ddddsssspppp))))

     tttteeeessssttttuuuunnnniiiittttrrrreeeeaaaaddddyyyy00000000((((ddddsssspppp))))
     rrrreeeeqqqquuuueeeessssttttsssseeeennnnsssseeee00003333((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, vvvvuuuu))))
     rrrreeeeaaaadddd00008888((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, llllbbbbaaaa,,,, vvvvuuuu))))
     wwwwrrrriiiitttteeee0000aaaa((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, llllbbbbaaaa,,,, vvvvuuuu))))
     iiiinnnnqqqquuuuiiiirrrryyyy11112222((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, vvvvuuuu))))
     mmmmooooddddeeeesssseeeelllleeeecccctttt11115555((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, ssssaaaavvvveeee,,,, vvvvuuuu))))
     mmmmooooddddeeeesssseeeelllleeeecccctttt55555555((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, ssssaaaavvvveeee,,,, vvvvuuuu))))
     rrrreeeesssseeeerrrrvvvveeeeuuuunnnniiiitttt11116666((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, ttttpppprrrr,,,, ttttppppddddiiiidddd,,,, eeeexxxxtttteeeennnntttt,,,, rrrreeeessssiiiidddd,,,, vvvvuuuu))))
     rrrreeeelllleeeeaaaasssseeeeuuuunnnniiiitttt11117777((((ddddsssspppp,,,, ttttpppprrrr,,,, ttttppppddddiiiidddd,,,, eeeexxxxtttteeeennnntttt,,,, rrrreeeessssiiiidddd,,,, vvvvuuuu))))
     mmmmooooddddeeeesssseeeennnnsssseeee1111aaaa((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, ppppaaaaggggeeeeccccttttrrrrllll,,,, ppppaaaaggggeeeeccccooooddddeeee,,,, vvvvuuuu))))
     mmmmooooddddeeeesssseeeennnnsssseeee5555aaaa((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, ppppaaaaggggeeeeccccttttrrrrllll,,,, ppppaaaaggggeeeeccccooooddddeeee,,,, vvvvuuuu))))
     mmmmooooddddeeeesssseeeennnnsssseeeeNNNNBBBB____5555aaaa((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, ppppaaaaggggeeeeccccttttrrrrllll,,,, ppppaaaaggggeeeeccccooooddddeeee,,,, vvvvuuuu))))
     sssseeeennnnddddddddiiiiaaaaggggnnnnoooossssttttiiiicccc1111dddd((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, sssseeeellllffff,,,, ddddooooffffllll,,,, uuuuooooffffllll,,,, vvvvuuuu))))

     rrrreeeeaaaaddddccccaaaappppaaaacccciiiittttyyyy22225555((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, llllbbbbaaaa,,,, ppppmmmmiiii,,,, vvvvuuuu))))
     rrrreeeeaaaaddddeeeexxxxtttteeeennnnddddeeeedddd22228888((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, llllbbbbaaaa,,,, vvvvuuuu))))
     wwwwrrrriiiitttteeeeeeeexxxxtttteeeennnnddddeeeedddd2222aaaa((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, llllbbbbaaaa,,,, vvvvuuuu))))

     ggggeeeettttffffdddd((((ddddsssspppp))))
     ddddoooossssccccssssiiiirrrreeeeqqqq((((ffffdddd,,,, ddddsssspppp))))
     vvvvooooiiiidddd ffffiiiillllllllgggg0000ccccmmmmdddd((((ddddsssspppp,,,, ccccmmmmddddbbbbuuuuffff,,,, bbbb0000,,,, ............,,,, bbbb5555))))
     vvvvooooiiiidddd ffffiiiillllllllgggg1111ccccmmmmdddd((((ddddsssspppp,,,, ccccmmmmddddbbbbuuuuffff,,,, bbbb0000,,,, ............,,,, bbbb9999))))
     vvvvooooiiiidddd ffffiiiillllllllgggg2222ccccmmmmdddd((((ddddsssspppp,,,, ccccmmmmddddbbbbuuuuffff,,,, bbbb0000,,,, ............,,,, bbbb9999))))
     vvvvooooiiiidddd ffffiiiillllllllgggg5555ccccmmmmdddd((((ddddsssspppp,,,, ccccmmmmddddbbbbuuuuffff,,,, bbbb0000,,,, ............,,,, bbbb11111111))))
     vvvvooooiiiidddd ffffiiiillllllllddddssssrrrreeeeqqqq((((ddddsssspppp,,,, ddddaaaattttaaaa,,,, ddddaaaattttaaaalllleeeennnn,,,, ffffllllaaaaggggssss))))
     vvvvooooiiiidddd vvvvttttoooossssttttrrrr((((vvvvaaaalllluuuueeee,,,, ttttaaaabbbblllleeee))))

     eeeexxxxtttteeeerrrrnnnn iiiinnnntttt ddddssssddddeeeebbbbuuuugggg;;;;
     eeeexxxxtttteeeerrrrnnnn iiiinnnntttt ddddssss____ddddeeeeffffaaaauuuulllltttt____ttttiiiimmmmeeeeoooouuuutttt;;;;
     eeeexxxxtttteeeerrrrnnnn lllloooonnnngggg ddddssssrrrreeeeqqqqffffllllaaaaggggssss;;;;
     DDDDSSSSDDDDBBBBGGGG((((ssssttttaaaatttteeeemmmmeeeennnntttt;;;; ............))))

     ssssttttrrrruuuucccctttt ddddssssrrrreeeeqqqq ****ddddsssspppp;;;;
     ssssttttrrrruuuucccctttt vvvvttttaaaabbbb ****ttttaaaabbbblllleeee;;;;
     cccchhhhaaaarrrr ****ooooppppaaaatttthhhh,,,, ****ccccmmmmddddbbbbuuuuffff,,,, ****ddddaaaattttaaaa;;;;
     cccchhhhaaaarrrr bbbb0000,,,, ............,,,, bbbb9999,,,, ddddooooffffllll,,,, eeeexxxxtttteeeennnntttt,,,, ppppaaaaggggeeeeccccooooddddeeee,,,, ppppaaaaggggeeeeccccttttrrrrllll,,,, ppppmmmmiiii,,,, rrrreeeessssiiiidddd,,,,
          ssssaaaavvvveeee,,,, sssseeeellllffff,,,, ttttppppddddiiiidddd,,,, ttttpppprrrr,,,, uuuuooooffffllll,,,, vvvvuuuu;;;;
     iiiinnnntttt ffffdddd,,,, ooooffffllllaaaaggggssss;;;;
     lllloooonnnngggg ddddaaaattttaaaalllleeeennnn,,,, llllbbbbaaaa,,,, vvvvaaaalllluuuueeee;;;;




                                                                        PPPPaaaaggggeeee 1111






ddddsssslllliiiibbbb((((3333XXXX))))                                                            ddddsssslllliiiibbbb((((3333XXXX))))



DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     These routines form the basis for a simplified interface to _d_s(7M)
     devices.  They are included in a program by compiling with the ----llllddddssss
     option.  An application would typically use _d_s_o_p_e_n, _d_s_c_l_o_s_e, and a set of
     command-specific routines such as _t_e_s_t_u_n_i_t_r_e_a_d_y_0_0.  The source to this
     library can be obtained by loading the _i_r_i_x__d_e_v._g_i_f_t_s._s_c_s_i subsystem,
     with the source code for the library in the files _d_s_t_a_b._c and _d_s_l_i_b._c in
     the directory /_u_s_r/_s_h_a_r_e/_s_r_c/_i_r_i_x/_e_x_a_m_p_l_e_s/_s_c_s_i.  There are also several
     sample programs using the dslib library in the same directory.

     The number of truly general SCSI commands is quite limited, so provision
     is made for supporting vendor-specific commands.  This is normally done
     by using one of the existing routines as a template, and creating a new
     routine of your own.  This might be useful if support for a SCSI command
     group other than Group 0, 1, 2, or 5 is needed.  It is expected that most
     non-trivial uses of the library will involve creating or modifying
     existing routines.  As of release 4.0 of IRIX, any SCSI command length
     from 1 to 12 bytes is supported by the underlying kernel drivers,
     providing the ds_cmdlen field is set correctly.

     A set of helper routines (_f_i_l_l_g_0_c_m_d and so on) are used as the basis for
     creating your own routines.  The utility function _d_s__s_h_o_w_c_m_d(_d_s_p) can be
     used to show information about the most recently executed command, in
     cases where the use of _d_s_d_e_b_u_g is too verbose.  _t_e_s_t_u_n_i_t_r_e_a_d_y_0_0, for
     instance, is implemented as:

          testunitready00(dsp)
          struct dsreq *dsp;
          {
            fillg0cmd(dsp, CMDBUF(dsp), G0_TEST, 0, 0, 0, 0, 0);
            filldsreq(dsp, 0, 0, DSRQ_READ|DSRQ_SENSE);
            return(doscsireq(getfd(dsp), dsp));
          }

     Note that many of these routines depend upon the exact setup of the _d_s_r_e_q
     structure used by _d_s_o_p_e_n.  It is therefore _n_o_t recommended that users
     attempt to use independently derived _d_s_r_e_q structures with them.

     _d_s_o_p_e_n passes _o_p_a_t_h and _o_f_l_a_g_s to the _o_p_e_n system call.  If the _o_p_e_n
     succeeds, _d_s_o_p_e_n allocates and fills a _d_s_r_e_q structure, along with some
     associated context information.  _d_s_c_l_o_s_e deallocates the specified _d_s_r_e_q
     structure, then calls _c_l_o_s_e to close the device.

     _f_i_l_l_g_0_c_m_d, _f_i_l_l_g_1_c_m_d, _f_i_l_l_g_2_c_m_d, and _f_i_l_l_g_5_c_m_d are used to fill Group 0,
     1, 2, and 5 command buffers, respectively.  _f_i_l_l_d_s_r_e_q fills a _d_s_r_e_q
     structure with commonly needed data.  The value of dsreqflags is ORed
     into the _d_s__f_l_a_g_s field.  This is useful if you want a flag (such as
     DSRQ_SENSE) set for some or all commands, as it allows you to avoid
     duplicating the library routines when you need a special flag set.  It
     also sets the default timeout (for functions that do not explicitly set a
     timeout).  The timeout is set from the global variable
     _d_s__d_e_f_a_u_l_t__t_i_m_e_o_u_t, and that variable is initialized to 10 seconds.  It



                                                                        PPPPaaaaggggeeee 2222






ddddsssslllliiiibbbb((((3333XXXX))))                                                            ddddsssslllliiiibbbb((((3333XXXX))))



     may be changed for applications that want longer default timeouts.
     Individual functions may still need to set longer (or shorter) timeouts,
     after calling _f_i_l_l_d_s_r_e_q.  _d_o_s_c_s_i_r_e_q issues the SCSI _i_o_c_t_l, performs a
     variety of error-handling functions, and returns the SCSI status byte.
     Also of interest on return is the ds_ret field, which is 0 on successful
     returns, and on failures indicates what type of error occurred (the
     DSRT_* values in <_s_y_s/_d_s_r_e_q._h>.

     _d_s__v_t_o_s_t_r Takes a value, and a table to look it up in.  If the value is
     found in the given table, a string describing the value is returned, else
     the empty string.  Five tables are provided:

     _d_s_r_q_n_a_m_e_t_a_b    for the DSRQ_* flags
     _d_s_r_t_n_a_m_e_t_a_b    for the DSRT_* flags
     _c_m_d_s_t_a_t_u_s_t_a_b   for the SCSI status byte return in ds_status
     _m_s_g_n_a_m_e_t_a_b     for the SCSI message bytes
     _c_m_d_n_a_m_e_t_a_b     for the SCSI commands, such as Testunitready (value is the
                    command byte; G0_TEST in this case)

     The _d_s_d_e_b_u_g variable, and the _D_S_D_B_G() macro can be used to enable debug
     _p_r_i_n_t_fs, and to add your own.  If the _d_s_d_e_b_u_g variable is non-zero,
     debugging information is printed by the library routines.  The _D_S_D_B_G
     macro is used for this purpose.  A more or less arbitrary sequence of
     statements can be used within the parentheses of the _D_S_D_B_G macro, but
     some form of print statement is most frequently used.

     Overlay structures define the layouts of the three (Group 0, 1, 6) Common
     Command Set command buffers.  Bytes are named both by position (g0_b0)
     and by typical function in the command buffer (g1_op_code).

     Mnemonic names are also defined for all CCS command codes (G0_TEST),
     message bytes (MSG_ABORT), and status bytes (STA_BUSY).  There are also a
     number of macros suitable for accessing _d_s_r_e_q structures, SCSI byte and
     bit fields, etc.

     A set of structures contains values, name strings, and descriptions for
     commonly used codes and values.  The structures document DSRQ_* and
     DSRT_* codes, CCS command codes, and CCS status and message bytes.  They
     are principally useful in generating explicit error messages.


     EXAMPLE PROGRAM

     The following code fragment illustrates simple use of the library, and of
     some /_d_e_v/_s_c_s_i support macros.  If you have installed the
     _4_D_g_i_f_t_s._s_r_c._f_u_l_l image, the full source code for this program can be
     found in the file /_u_s_r/_p_e_o_p_l_e/_4_D_g_i_f_t_s/_e_x_a_m_p_l_e_s/_d_e_v_i_c_e_s/_d_e_v_s_c_s_i/_i_n_q_u_i_r_e._c,

          while (--argc > 0) {
            fn = *++argv;
            printf("%-17s  ", fn);
            if ((dsp = dsopen(fn, O_RDONLY)) == NULL) {



                                                                        PPPPaaaaggggeeee 3333






ddddsssslllliiiibbbb((((3333XXXX))))                                                            ddddsssslllliiiibbbb((((3333XXXX))))



            fflush(stdout);
              perror("cannot open");
              continue;
            }

            if(inquiry12(dsp, inqbuf, sizeof inqbuf, 0) != 0)
              printf("%-10s inquiry failure0, "---");
            else {
              pdt = DATABUF(dsp)[0] & 0x7F;
              if (DATASENT(dsp) >= 1)
                printf("%-10s", pdt_types[(pdt<NPDT) ? pdt : NPDT-1]);
              if (DATASENT(dsp) >= 16) printf("  %-12.8s", &DATABUF(dsp)[8]);
              if (DATASENT(dsp) >= 32) printf("  %.16s",   &DATABUF(dsp)[16]);
              if (DATASENT(dsp) >= 36) printf("  %.4s",    &DATABUF(dsp)[32]);
              /*  do test unit ready only if inquiry successful, since many
                devices, such as tapes, return inquiry info, even if
                not ready (i.e., no tape in a tape drive). */
              if(testunitready00(dsp) != 0) {
                printf("  %s0,
                  (RET(dsp)==DSRT_NOSEL) ? "cannot select" : "not ready");
              }
              else
                printf("  ready0);
            }
            dsclose(dsp);
          }

     Each device is opened, and the necessary data structures created.  An
     inquiry is done to see if the device exists; if so, it's type is printed.
     A test unit ready is done to see if the device is ready for I/O.
     Finally, the device is closed, releasing the data structures.  The normal
     output is of the form:

          /dev/scsi/sc0d2l0   Tape     ARCHIVE       VIPER 150  21247  -605  not ready


DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     _d_s_o_p_e_n returns a NNNNUUUULLLLLLLL pointer on failure.  _d_o_s_c_s_i_r_e_q returns -1 on
     absolute failure, and the status byte otherwise.  A status byte of 0xff
     indicates an invalid status byte because the scsi command didn't
     complete.  The RET(dsp) macro returns a result code, which can be
     consulted for any error or 'unusual' status from the driver; a value of 0
     indicates a normal return.

NNNNOOOOTTTTEEEE
     A common failure occurs when the byte count passed to the dslib routines
     doesn't match the byte count implied by the values in the SCSI command
     descriptor (as filled by _f_i_l_l_g_0_c_m_d and so on).  This is particularly
     common with _r_e_a_d_0_8,_w_r_i_t_e_0_a,_r_e_a_d_e_x_t_e_n_d_e_d_2_8, and _w_r_i_t_e_e_x_t_e_n_d_e_d_2_a.  This is
     because these commands occur in a number of device specific forms.  If
     you get console error messages similar to




                                                                        PPPPaaaaggggeeee 4444






ddddsssslllliiiibbbb((((3333XXXX))))                                                            ddddsssslllliiiibbbb((((3333XXXX))))



          SCSI Bus=# ID=# LUN=#: Too much data (probable SCSI bus cabling problem)

     then you are probably seeing this kind of mismatch.  See the comments in
     the _d_s_l_i_b._c source file for more information.

     As of IRIX 5.1, this library and the underlying driver are supported on
     all Silicon Graphics SCSI adapters (wd93, wd95, and jag) for all
     controllers that are installed.  Prior to that release, it was supported
     only on the wd93 controller.

     As of IRIX 5.1, devices can be open via both the _d_s and other high level
     drivers at the same time (except for _t_p_s_c).  Only one program can have
     any _d_s device open at a time, however.

FFFFIIIILLLLEEEESSSS
     /dev/scsi/*

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     hinv(1M), ds(7M).

     IRIX Device Driver Programmer's Guide


































                                                                        PPPPaaaaggggeeee 5555